The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / progem.lzh / wind15.prf < prev next >

Wrap

Text File | 1987-06-23 | 13.9 KB | 282 lines

.!**************************************************************************** .! .! ANTIC PUBLISHING INC., COPYRIGHT 1985. REPRINTED BY PERMISSION. .! .! ** Professional GEM ** by Tim Oren .! .! Proff File by ST enthusiasts at .! Case Western Reserve University .! Cleveland, Ohio .! uucp : decvax!cwruecmp!bammi .! csnet: bammi@case .! arpa : bammi%case@csnet-relay .! compuserve: 71515,155 .! .!**************************************************************************** .! .! .!**************************************************************************** .! .! Begin Part XV .! .!**************************************************************************** .! .PART XV Coping with GEMDOS .PP While it's fun playing with windows and object trees, one of the day-to-day realities of working with the ST is its operating system, GEMDOS. A successful application should insulate the user from the foibles and occasional calamities of the machine's file system. The GEM environment provides some minimal tools for doing this, but a good deal of responsibility still rests with you, the programmer. .PP This column (#15 in the ST PRO GEM series) tries to address the GEM/DOS integration problem by providing you some stock code for common functions, along with a discussion of some of the worst "gotchas" lurking for the unwary. The download for this column is GMCL15.C, and it can be found in DL3 of PCS-58. You should obtain and list this file before proceeding. .SH A BIT OF HISTORY. There has been a good deal of confusion in the Atari press and among developers over what GEMDOS is, and how it relates to TOS and CP/M-68K. It's important to clear this up, so you can get a true picture of what GEMDOS is intended to do. The best way is to tell the story of GEMDOS' origins, which I can do, because I was there. .PP As most developers are aware, GEM was first implemented on the IBM PC. PC GEM performed two functions. The first was a windowed graphics extension to the PC environment. The second was a visual shell, the Desktop, which ran on top of the existing operating system, PC-DOS. .PP When work started on moving GEM to the ST, there were two big problems. First, no STs actually existed. Second, there was no operating system on the 68000 with which GEM and the Desktop could run. Unix was too large, and CP/M-68K lacked a number of capabilities, such as hierarchical files, which were needed to support GEM. .PP Work on porting the graphics parts of GEM to the 68000 had to start immediately to meet schedules. Therefore, CP/M-68K running on Apple Lisa's was used to get this part of the project off the ground. Naturally, the Alcyon C compiler and other tools which were native to this environment were used. .PP In parallel, an effort was begun to write a new operating system for the 68000, which would ultimately become the ST's file system. It was designed to be a close clone of PC-DOS, since it would perform the same functions for GEM in the new environment. At this point, the term TOS was introduced. TOS really meant "the operating system, whatever it may be, that will run on the ST", since not even the specifications, let alone the code, were complete at that time. .PP The first engineer to work on "TOS" at Digital Research was Jason Loveman. This name leaked to the press, and in some distorted fashion generated a rumor about "Jason DOS", which was still just the same unfinished project. As "TOS" became more solid, the developer's tools were ported to the new environment one by one, and the GEM programming moved with them. CP/M-68K was completely abandoned, though the old manuals for C and the tools lived on and are still found in the Atari developer's kit. .PP All of this work had been done on Lisas or Compupro systems fitted with 68000 boards. At this point, workable ST prototypes became available. An implementation of "TOS" for the target machine was begun, even before the basic operating system was fully completed. .PP The other intent for the new operating system was to be a base for GEM on other 68000 systems as well as the ST. Because of this, Digital Research named it GEMDOS when it was finally complete, thus providing the final bit of nomenclature. "TOS" as now found in the ST is in fact a particular implementation of generic GEMDOS, including the ST specific BIOS. .PP So, GEMDOS is a PC-DOS clone, but, not quite. There are enough differences to cause problems if they are ignored. (Remember, it looks like a duck, and quacks like a duck, but it's not a duck.) .SH GOING FOR IT. As a first example, consider the routines open_file() and create_file() at the beginning of the download. They make use of the GEMDOS calls Fopen() and Fcreate(). You will notice that these names are not the ones specified in the Digital Research GEMDOS manual. Developers who have used PC GEM will also observe that they are radically different from the function names in the PC-DOS bindings. .PP In fact, all of the GEMDOS function calls on the ST are defined as macros in the file osbind.h, distributed with the developer's kit. At compile time they are turned into calls to the assembly language routine gemdos(), part of the osbind.o binary. So, if you find the naming conventions to be particularly offensive for some reason, just edit the appropriate macros in osbind.h. .PP In DRI's PC-DOS bindings, any error codes were returned in the global variable DOS_ERR. In the GEMDOS bindings, the operation result or an error code is returned as the value of the calling function. In the case of Fopen() and Fcreate(), the result is a valid file handle if it is positive. A negative result is always an error code, indicating that the operation failed. .PP An application which encounters a GEMDOS error should display an alert, and query for retry or abort. The type of loop structure exemplified by open_file() and create_file() should be usable with most GEMDOS functions which might fail. The AES provides a function, form_error, which implements a set of "canned" error alerts appropriate to the various possible errors. .PP However, this is where the fun starts. For unknown reasons, the form_error on the ST expects to see PC-DOS, not GEMDOS, error codes as it's input! Therefore you need a routine to translate one into the other. The routine dos_error() in the download provides this function. The GEMDOS errors are in the same sequence as those for PC-DOS, but their numerical order is reversed and shifted. Notice also that dos_error() does NOT perform the translation if the error code is less than -50. These codes have no PC-DOS equivalent; computing a bogus translation will cause form_error to crash. Instead, they are passed through verbatim, resulting in a "generic" alert which gives only the error number. .PP The other major task in integrating a GEM application with the file system is selecting file names for input and output. Again, the AES provides some assistance with the fsel_input call, which invokes the standard file selector dialog. .PP There are several drawbacks to the standard file selector. One is that the "ITEM SELECTOR" title is constant and cannot be changed by the application. This could cause confusion for the user, since it may not be clear which of several functions, closely spaced in the FILE menu, was actually invoked. While it might be possible to find and "rewire" the AES resource that defines the file selector, it is unlikely that such an approach would be portable to a later version of ST GEM. .PP A viable approach to eliminating confusion is to display a small "marquee" box, with a message defining the operation, on the screen just above the file selector. To do this, you must initialize the location of the box so that it is outside of the file selector's bounds, and then draw it just before invoking the file selector. This way they will appear together. Before returning to its main event loop, the application should post a redraw message for the "marquee" area. The AES will merge this redraw with the one generated by fsel_input, and the result will be received by the application's evnt_multi. .PP Another problem with the file selector is that it resets your application's virtual workstation clip rectangle without warning. There are other AES functions, such as objc_draw, which also do this, but the file selector can be troublesome because it may be the only AES call used by some VDI-based ST applications. .PP The veteran developer will also notice that the file selector takes and returns the path and filename as two separate strings, while the GEMDOS file functions require a fully pathed file name. Also, the file selector doesn't remember its "home" directory; you are responsible for determining the default directory, and keeping track of any changes. The remainder of the download and column is devoted to set of utilities which should alleviate some of the "grunt work" of these chores. .PP The top level routine in this collection is get_file(). It is called with two string arguments. The first must point to a four byte string area containing the desired file name extension (three characters plus a null). The second is the default file name. .PP If the default file name is non-null, then get_file() invokes parse_fname() to break it into path and name. Parse_fname() also adds the necessary "wild card" file specification to the path, using the extent name given as input. .PP If no default file was supplied, or the default did not contain a path, the routine get_path() is invoked to find the current default directory and construct a legal path string for it. .PP The results of these manipulations are supplied to fsel_input. Notice that the result of the file selector is returned via its third argument, rather than as a function value. If the result is TRUE, get_file() merges the temporary path and file string, storing the result via the second input parameter. This result string is suitable for use with Fopen, and may be resubmitted to get_file() when the next operation is invoked by the user. .PP Parse_fname() is straight-forward C. It looks backward along the file to find the first character which is part of the path. The tail of the filename is copied off, and its former location is overlaid with the wild card specification. Get_path() is a bit more interesting. It makes use of two GEMDOS functions, Dgetdrv() and Dgetpath() to obtain the default disk drive and directory, respectively. Note that Dgetpath() will return a null string if the current default is the root, but it puts a back-slash at the beginning of the path otherwise. This forces a check for insertion in the root case, since the file selector wants to see something like "A:\*.RSC", rather than "A:*.RSC". After making this fix, get_path() concatenates the wild card specification derived from the input extent. .PP The last routine in the download is new_ext(). This utility is useful if your application uses more than one associated file at a time. For instance, the Resource Construction Set uses both an RSC and a DEF file, with the same base name. New_ext() takes a fully formed file name, and replaces its old extent with the new one which you supply. This lets you quickly generate both file names after one call to the file selector. Notice that new_ext() looks BACKWARD along the name to find the delimiting period, since this character can also be part of a subdirectory name in the path. .PP So we reach the end of the code and this column. Hopefully both will keep you profitably occupied for a while. July's column will return to graphics topics, with a look at writing customized rubber box and drag box routines, and ways to implement your own "pop-up" menus. August will bring techniques for displaying progress indicators, associating dialog and menu entries with keystrokes, and customizing objc_edit. .SH I CAN'T HEAR YOU! The Feedback mailbag has been noticably flat of late. There have been a number of compliments on the column, which are much appreciated, and some suggestions for topics which fall outside the bounds of this series. The latter have been passed on to Antic for possible inclusion in their new ST quarterly, START. .PP One recurring problem is finding the downloads. A number of the earlier columns say they are in PCS-132 (the old SIG*ATARI), and one says PCS-57 (mea culpa). In fact, ALL of the downloads are now in DL3 of PCS-58 (ATARI16). Filenames for first nine columns are all in the form GEMCLx.C, where x is the column's digit. For reasons unknown to me, the next two files were named GEMC10.C and GEMC11.C; the latest two downloads are called GMCL13.C and GMCL15.C. The latter naming pattern should continue into the future. .PP Undoubtedly, one reason for the shortage of questions is the amazing ability to get a quick answer on the Developer's SIG, PCS- 57. This is a good sign of a strong Atari community on Compuserve. However, the SIG message style doesn't really lend itself to lengthy explanation, so suggestions for longer topics are always welcome here. .PP Finally, I am now beginning the process of collecting these columns and some additional material into a book. In doing so, it would be helpful to know if you feel that any part of GEM has been slighted in my discussions. If so, let me know. Your suggestions will appear in future columns and finally make their way into the book. .! .! .!***************************************************************************** .!* * .!* End Part 15 * .!* * .!*****************************************************************************